home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / utilities / pu630.dms / pu630.adf / Libs / OwnDevUnit.doc < prev    next >
Text File  |  1993-02-13  |  9KB  |  270 lines
  1. TABLE OF CONTENTS
  2.  
  3.   OwnDevUnit.library/AttemptDevUnit
  4.   OwnDevUnit.library/AvailDevUnit
  5.   OwnDevUnit.library/FreeDevUnit
  6.   OwnDevUnit.library/LockDevUnit
  7.   OwnDevUnit.library/NameDevUnit
  8.  
  9.  
  10. OwnDevUnit.library/AttemptDevUnit                         May 25, 1991  23:05
  11.  
  12.   NAME
  13.       AttemptDevUnit --- Attempt to lock a device/unit
  14.  
  15.   SYNOPSIS
  16.       Failure = AttemptDevUnit( Device, Unit, OwnerName , NotifyBit );
  17.       d0                        a0      d0    a1          d1.b
  18.  
  19.       UBYTE   *Failure;
  20.       UBYTE   *Device;
  21.       ULONG    Unit;
  22.       UBYTE   *OwnerName;
  23.       UBYTE    NotifyBit;
  24.  
  25.   FUNCTION
  26.       This function will attempt to lock the specified device/unit.  It will
  27.       wait a maximum of five seconds for the device/unit to become free.
  28.       This delay is to allow an owner that has requested notification to get
  29.       off the device when the attempt is made.  This function is intended
  30.       for interactive use where blocking indefinitely is undesirable.
  31.  
  32.   INPUTS
  33.       Device
  34.           A pointer to the name of the device you wish to lock.
  35.  
  36.       Unit
  37.           The unit number of the device you wish to lock.
  38.  
  39.       OwnerName
  40.           A pointer to a name returned to the caller of AttemptDevUnit()
  41.           when you refuse to give up the lock to someone else.
  42.  
  43.       NotifyBit
  44.           Some programs, such as Getty, sit on a device waiting for a call
  45.           to come in.  It is to their advantage to know when someone else
  46.           wants the device so that they can release the lock.  This would
  47.           allow someone to use a term program, for instance, and not have to
  48.           specifically shut down the program sitting on the device.
  49.  
  50.           If you wish to be notified when someone tries to lock the de-
  51.           vice/unit you own, pass a signal bit number, as returned by
  52.           AllocSignal(), in this argument.  When someone tries to lock the
  53.           device/unit, your task will be signaled.  Passing a zero in this ar-
  54.           gument indicates that you do not wish to be notified when someone
  55.           requests the device.
  56.  
  57.   RETURNS
  58.       If the device/unit is successfully locked, NULL is returned.  If
  59.       someone else owns the device, a pointer to their OwnerName is re-
  60.       turned.  If an internal error occurred, a pointer to an error message
  61.       is returned.
  62.  
  63.       All error messages begin with ODUERR_LEADCHAR. This allows one to
  64.       quickly check if the returned value is an error message or owner name.
  65.       The possible errors are:
  66.  
  67.       ODUERR_NOMEM   --  An out of memory condition occurred while attempting
  68.                          to lock the device.
  69.  
  70.       ODUERR_NOTIMER --  The timer.device could not be opened while attempt-
  71.                          ing to lock the device.
  72.  
  73.       ODUERR_BADNAME --  An invalid device name was supplied.  This occurs
  74.                          only when Device is NULL.
  75.  
  76.       ODUERR_BADBIT  --  An invalid notify bit was supplied.  This occurs
  77.                          only when NotifyBit equals -1.
  78.  
  79.       ODUERR_UNKNOWN --  Not strictly an error.  This occurs when the lock
  80.                          could not be granted, but the name of the current
  81.                          owner is NULL.
  82.  
  83.   BUGS
  84.       None know.
  85.  
  86.   SEE ALSO
  87.       LockDevUnit(), exec.library/AllocSignal()
  88.  
  89. OwnDevUnit.library/AvailDevUnit                           May 25, 1991  23:05
  90.  
  91.   NAME
  92.       AvailDevUnit --- Quickly check the availability of a device/unit
  93.  
  94.   SYNOPSIS
  95.       Truth = AvailDevUnit( Device, Unit);
  96.       d0                    a0      d0
  97.  
  98.       BOOL     Truth;
  99.       UBYTE   *Device;
  100.       ULONG    Unit;
  101.  
  102.   FUNCTION
  103.       This function will quickly determine if a device/unit is currently
  104.       available (i.e., not locked).  It does not perform a lock.  It is
  105.       intended for cases where one must wait for a device/unit to become
  106.       free, but because of the nature of the code, waiting the five seconds
  107.       AttempDevUnit() takes to return is undesirable.
  108.  
  109.   INPUTS
  110.       Device
  111.           A pointer to the name of the device you wish to check.
  112.  
  113.       Unit
  114.           The unit number of the device you wish to check.
  115.  
  116.   RETURNS
  117.       If the device/unit is currently available, TRUE is returned.  If it is
  118.       currently locked, FALSE is returned.
  119.  
  120.   BUGS
  121.       None known.
  122.  
  123.   SEE ALSO
  124.       AttemptDevUnit()
  125.  
  126. OwnDevUnit.library/FreeDevUnit                            May 25, 1991  23:05
  127.  
  128.   NAME
  129.       FreeDevUnit --- Release a lock on a device/unit
  130.  
  131.   SYNOPSIS
  132.       FreeDevUnit(Device , Unit);
  133.                   a0       d0
  134.  
  135.       UBYTE   *Device;
  136.       ULONG    Unit;
  137.  
  138.   FUNCTION
  139.       Releases a lock on a device/unit previously attained by a call to
  140.       AttemptDevUnit() or LockDevUnit().  This function must be called
  141.       from the same task context that the lock was attained under or the
  142.       device/unit will not be freed!
  143.  
  144.   INPUTS
  145.       Device
  146.           A pointer to the name of the device you wish to release.
  147.  
  148.       Unit
  149.           The unit number of the device you wish to release.
  150.  
  151.   RETURNS
  152.       None.
  153.  
  154.   BUGS
  155.       None known.
  156.  
  157.   SEE ALSO
  158.       AttemptDevUnit(), FreeDevUnit()
  159.  
  160. OwnDevUnit.library/LockDevUnit                            May 25, 1991  23:05
  161.  
  162.   NAME
  163.       LockDevUnit --- Block until a lock on a device/unit is granted
  164.  
  165.   SYNOPSIS
  166.       Failure = LockDevUnit( Device, Unit, OwnerName , NotifyBit );
  167.       d0                     a0      d0    a1          d1.b
  168.  
  169.       UBYTE   *Failure;
  170.       UBYTE   *Device;
  171.       ULONG    Unit;
  172.       UBYTE   *OwnerName;
  173.       UBYTE    NotifyBit;
  174.  
  175.   FUNCTION
  176.       This function will block until a lock on the specified device/unit is
  177.       granted.  It is intended for non-interactive use.
  178.  
  179.   INPUTS
  180.       Device
  181.           A pointer to the name of the device you wish to lock.
  182.  
  183.       Unit
  184.           The unit number of the device you wish to lock.
  185.  
  186.       OwnerName
  187.           A pointer to a name returned to the caller of AttemptDevUnit()
  188.           when you refuse to give up the lock to someone else.
  189.  
  190.       NotifyBit
  191.           Some programs, such as Getty, sit on a device waiting for a call
  192.           to come in.  It is to their advantage to know when someone else
  193.           wants the device so that they can release the lock.  This would
  194.           allow someone to use a term program, for instance, and not have to
  195.           specifically shut down the program sitting on the device.
  196.  
  197.           If you wish to be notified when someone tries to lock the de-
  198.           vice/unit you own, pass a signal bit number, as returned by
  199.           AllocSignal(), in this argument.  When someone tries to lock the
  200.           device/unit, your task will be signaled.  Passing a zero in this ar-
  201.           gument indicates that you do not wish to be notified when someone
  202.           requests the device.
  203.  
  204.   RETURNS
  205.       If the device/unit is successfully locked, NULL is returned.  If an
  206.       internal error occurred, a pointer to an error message is returned.
  207.  
  208.       All error messages begin with ODUERR_LEADCHAR. This allows one to
  209.       quickly check if the returned value is an error message or owner name.
  210.       The possible errors are:
  211.  
  212.       ODUERR_NOMEM   --  An out of memory condition occurred while attempting
  213.                          to lock the device.
  214.  
  215.       ODUERR_NOTIMER --  The timer.device could not be opened while attempt-
  216.                          ing to lock the device.
  217.  
  218.       ODUERR_BADNAME --  An invalid device name was supplied.  This occurs
  219.                          only when Device is NULL.
  220.  
  221.       ODUERR_BADBIT  --  An invalid notify bit was supplied.  This occurs
  222.                          only when NotifyBit equals -1.
  223.  
  224.   BUGS
  225.       None know.
  226.  
  227.   SEE ALSO
  228.       AttemptDevUnit(), exec.library/AllocSignal()
  229.  
  230. OwnDevUnit.library/NameDevUnit                            May 25, 1991  23:05
  231.  
  232.   NAME
  233.       NameDevUnit --- Change the owner name value of a locked device/unit
  234.  
  235.   SYNOPSIS
  236.       NameDevUnit(Device , Unit, OwnerName );
  237.                   a0       d0    a1
  238.  
  239.       UBYTE   *Device;
  240.       ULONG    Unit;
  241.       UBYTE   *OwnerName;
  242.  
  243.   FUNCTION
  244.       This allows one to change the owner name returned by AttemptDevUnit().
  245.       You must own the lock on the specified device/unit or this function
  246.       will do nothing.
  247.  
  248.       This function is intended for programs such as Getty, which sit on a
  249.       device and launch other programs as calls are detected.
  250.  
  251.   INPUTS
  252.       Device
  253.           A pointer to the name of the device you wish to alter.
  254.  
  255.       Unit
  256.           The unit number of the device you wish to alter.
  257.  
  258.       OwnerName
  259.           A pointer to a name returned to the caller of AttemptDevUnit()
  260.           when you refuse to give up the lock to someone else.
  261.  
  262.   RETURNS
  263.       None.
  264.  
  265.   BUGS
  266.       None known.
  267.  
  268.   SEE ALSO
  269.       AttemptDevUnit()
  270.